oracle.pgx.config

## Class PgxConfig

- java.lang.Object
- - oracle.pgx.config.AbstractConfig
  - - oracle.pgx.config.AbstractPgxConfig
    - - oracle.pgx.config.PgxConfig

-     @Generated(value="config_generator.py")
      public class PgxConfig
      extends AbstractPgxConfig

  PGX Engine Config

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `PgxConfig.Field` Fields of PGX Engine Config

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ArrayFactoryStrategy` | `getArrayFactoryStrategy()` `java_arrays` = use normal java arrays only (limited to 32bit in length) `java_2d_arrays` = use Java 2D arrays only (achieve arrays of 64bit in length with the cost of indirection) `off_heap_arrays` = use arrays allocated off-heap (achieve 64bit in length without performance penalty, but with the price of breaking out of the JVM) `dynamic` = decide at run-time which allocation strategy to use based on the requested array length
    `Integer` | `getBfsThresholdReadBased()` threshold of BFS traversal level items to switch to read-based visiting strategy
    `Integer` | `getBfsThresholdSingleThreaded()` until what number of BFS traversal level items vertices are visited single-threaded
    `Integer` | `getBigPartitionThreshold()` the threshold for partitions to be considered 'big'.
    `String` | `getCc()` (only relevant if native analysis is enabled) C++ compiler executable (either absolute path or resolvable via `$PATH`)
    `String` | `getCflags()` (only relevant if native analysis is enabled) flags for C++ compiler
    `Charset` | `getCharset()` Gets the charset.
    `Integer` | `getCniDiffFactorDefault()` default diff factor value used in the common neighbor iterator implementations.
    `Integer` | `getCniSmallDefault()` default value used in the common neighbor iterator implementations, to indicate below which threshold a subarray is considered small.
    `Integer` | `getCniStopRecursionDefault()` default value used in the common neighbor iterator implementations, to indicate the minimum size where the binary search approach is applied.
    `Integer` | `getDfsThresholdLarge()` value that determines at which number of visited vertices the DFS implementation will switch to data-structures that are more optimized for larger numbers of vertices.
    `List<String>` | `getGraphs()` list of paths to graph configs to be registered at start-up
    `Integer` | `getIdleSleepDuration()` if engine is idle, duration in milliseconds the dispatcher thread sleeps until checking for new tasks again
    `List<String>` | `getInvokeableProviders()` list of invokeable providers to be loaded during startup
    `ArrayFactoryStrategy` | `getLargeArrayStrategy()` [relevant for `dynamic` array factory only] array factory strategy to use when requested array size is exceeding `large_array_threshold`
    `Integer` | `getLargeArrayThreshold()` [relevant for `dynamic` array factory only] use `large_array_strategy` when requested array size is exceeding this number.
    `String` | `getLflags()` (only relevant if native analysis is enabled) linker flags for C++ compiler
    `Integer` | `getMaxActiveSessions()` the maximum number of sessions allowed to be active at a time
    `Integer` | `getMaxOffHeapSize()` maximum amount of off-heap memory PGX is allowed to allocate in megabytes, before an OutOfMemoryError will be thrown.
    `Integer` | `getMaxQueueSizePerSession()` the maximum number of pending tasks allowed to be in the queue, per session.
    `Integer` | `getMaxSnapshotCount()` Number of snapshots that may be loaded in the engine at the same time.
    `Integer` | `getMemoryCleanupInterval()` memory cleanup tick in seconds
    `Integer` | `getNumSpinLocks()` how many spin locks each generated app will create at instantiation.
    `Integer` | `getNumWorkersAnalysis()` how many worker threads to use for analysis tasks
    `Integer` | `getNumWorkersFastTrackAnalysis()` how many worker threads to use for fast-track analysis tasks
    `Integer` | `getNumWorkersIo()` how many worker threads to use for I/O tasks (load/refresh/write from/to disk).
    `Integer` | `getParallelism()` number of worker threads to be used in thread pool.
    `ParallelizationStrategy` | `getParallelizationStrategy()` which parallelization strategy to use.
    `String` | `getPathToGmCompiler()` if set, use this path to `gm_comp` binary for dynamic compilations.
    `Double` | `getReleaseMemoryThreshold()` threshold percentage of used memory after which the engine starts freeing un-used graphs.
    `Integer` | `getSessionIdleTimeoutSecs()` timeout of idling sessions in seconds.
    `Integer` | `getSessionTaskTimeoutSecs()` timeout to interrupt long-running tasks submitted by sessions (algorithms, I/O tasks) in seconds.
    `Integer` | `getSmallTaskLength()` task length if total amount of work is small than default task length (only relevant for task-stealing strategies)
    `Integer` | `getTaskLength()` default task length (only relevant for task-stealing strategies).
    `String` | `getTmpDir()` Use this path as temporary directory to store compilation artifacts and other temporary data.
    `Map<PgxConfig.Field,Object>` | `getValues()` Gets the parsed values.
    `Map<PgxConfig.Field,Object>` | `getValuesWithoutDefaults()` Gets the values without defaults.
    `boolean` | `hasDefaultValue(PgxConfig.Field field)` Checks for default value.
    `Boolean` | `isAllowIdleTimeoutOverwrite()` if `true`, sessions can overwrite default idle timeout
    `Boolean` | `isAllowTaskTimeoutOverwrite()` if `true`, sessions can overwrite default task timeout
    `Boolean` | `isEnableGmCompiler()` if `true`, enable dynamic compilation of Green-Marl code during runtime.
    `Boolean` | `isExplicitSpinLocks()` `true` means spin explicitly in a loop until lock becomes available.
    `Boolean` | `isLaunchWatchdogs()` (for debugging) if `true`, additional watch-dog threads will be launched which monitor and log engine health stats
    `Boolean` | `isStrictMode()` if `true`, exceptions are thrown and logged with `ERROR` level whenever engine encounters configuration problems, such as invalid keys, mismatches and other potential errors.
    `Boolean` | `isThrowOutOfMemoryErrorDuringAllocation()` (for debugging) if `true`, engine will throw OutOfMemoryErrors on purpose when trying to allocate large memory chunks.
    `Boolean` | `isThrowOutOfMemoryErrorDuringLoading()` (for debugging) if `true`, engine will throw OutOfMemoryErrors on purpose when trying to load graphs from disk.
    `Boolean` | `isThrowOutOfMemoryErrorDuringMutation()` (for debugging) if `true`, engine will throw OutOfMemoryErrors on purpose when trying to mutate graphs.
    `Boolean` | `isUnsafeAllowForeignSyntax()` (This flag reduces security, enable only if you know what you're doing!) Allow foreign syntax in user-provided Green-Marl programs
    `Boolean` | `isUnsafeAllowLocalFilesystem()` (This flag reduces security, enable only if you know what you're doing!) Allow loading from local filesystem, if in client/server mode.
    `Boolean` | `isUseNativeAnalysis()` execute analyses using Java (`false`) or C++ (`true`) runtime
    `Boolean` | `isUseNativeLoaders()` use Java (`false`) or C++ (`true`) graph loader framework
    `Boolean` | `isUseStringPool()` If `true`, PGX will store string properties in a pool in order to consume less memory on string properties
    `static PgxConfig` | `parse(InputStream is, boolean strict, File parent)` Parses an input stream.
    `static PgxConfig` | `parse(Map<String,Object> raw, boolean strict, File parent)` Parses a raw key/value mapping.
    `static PgxConfig` | `parse(Properties props, boolean strict)` Parses a properties file.
    `String` | `toString()`

    - ### Methods inherited from class oracle.pgx.config.AbstractPgxConfig

      `get, getConfigValues, init, isInitialized, reset, strict`

    - ### Methods inherited from class oracle.pgx.config.AbstractConfig

      `setSerializable`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### getArrayFactoryStrategy

          public ArrayFactoryStrategy getArrayFactoryStrategy()

      `java_arrays` = use normal java arrays only (limited to 32bit in length)
      `java_2d_arrays` = use Java 2D arrays only (achieve arrays of 64bit in length with the cost of indirection)
      `off_heap_arrays` = use arrays allocated off-heap (achieve 64bit in length without performance penalty, but with the price of breaking out of the JVM)
      `dynamic` = decide at run-time which allocation strategy to use based on the requested array length

    - #### getBfsThresholdReadBased

          public Integer getBfsThresholdReadBased()

      threshold of BFS traversal level items to switch to read-based visiting strategy

    - #### getBfsThresholdSingleThreaded

          public Integer getBfsThresholdSingleThreaded()

      until what number of BFS traversal level items vertices are visited single-threaded

    - #### getBigPartitionThreshold

          public Integer getBigPartitionThreshold()

      the threshold for partitions to be considered 'big'. If a partition contains more vertices than specified in this threshold, PGX will use special, read-only vertex set implementation to hold the vertices which trades memory for speed. Advantage of big partitions: 1) almost no additional memory needed to hold the vertices 2) creation time of partition results is a lot faster. Disadvantages of big partitions: 1) read-only (adding vertices to a big partition will result in an exception) 2) retrieving the vertices (iteration over a big partiton) is slightly slower.

    - #### getCc

          public String getCc()

      (only relevant if native analysis is enabled) C++ compiler executable (either absolute path or resolvable via `$PATH`)

    - #### getCflags

          public String getCflags()

      (only relevant if native analysis is enabled) flags for C++ compiler

    - #### getCharset

          public Charset getCharset()

      Gets the charset.
      Returns:
        the charset

    - #### getCniDiffFactorDefault

          public Integer getCniDiffFactorDefault()

      default diff factor value used in the common neighbor iterator implementations.

    - #### getCniSmallDefault

          public Integer getCniSmallDefault()

      default value used in the common neighbor iterator implementations, to indicate below which threshold a subarray is considered small.

    - #### getCniStopRecursionDefault

          public Integer getCniStopRecursionDefault()

      default value used in the common neighbor iterator implementations, to indicate the minimum size where the binary search approach is applied.

    - #### getDfsThresholdLarge

          public Integer getDfsThresholdLarge()

      value that determines at which number of visited vertices the DFS implementation will switch to data-structures that are more optimized for larger numbers of vertices.

    - #### getGraphs

          public List<String> getGraphs()

      list of paths to graph configs to be registered at start-up

    - #### getIdleSleepDuration

          public Integer getIdleSleepDuration()

      if engine is idle, duration in milliseconds the dispatcher thread sleeps until checking for new tasks again

    - #### getInvokeableProviders

          public List<String> getInvokeableProviders()

      list of invokeable providers to be loaded during startup

    - #### getLargeArrayStrategy

          public ArrayFactoryStrategy getLargeArrayStrategy()

      [relevant for `dynamic` array factory only] array factory strategy to use when requested array size is exceeding `large_array_threshold`

    - #### getLargeArrayThreshold

          public Integer getLargeArrayThreshold()

      [relevant for `dynamic` array factory only] use `large_array_strategy` when requested array size is exceeding this number. (defaults to `Integer.MAX_VALUE - 3`)

    - #### getLflags

          public String getLflags()

      (only relevant if native analysis is enabled) linker flags for C++ compiler

    - #### getMaxActiveSessions

          public Integer getMaxActiveSessions()

      the maximum number of sessions allowed to be active at a time

    - #### getMaxOffHeapSize

          public Integer getMaxOffHeapSize()

      maximum amount of off-heap memory PGX is allowed to allocate in megabytes, before an OutOfMemoryError will be thrown. Note: this limit is not guaranteed to never be exceeded because of rounding and synchronization trade-offs. It only serves as threshold when PGX starts to reject new memory allocation requests.

    - #### getMaxQueueSizePerSession

          public Integer getMaxQueueSizePerSession()

      the maximum number of pending tasks allowed to be in the queue, per session. If a session reaches the maximum, new incoming requests of that sesssion get rejected. A negative value means infinity / unlimited.

    - #### getMaxSnapshotCount

          public Integer getMaxSnapshotCount()

      Number of snapshots that may be loaded in the engine at the same time. New snapshots can be created via auto or forced update. If the number of snapshots of a graph reaches this threshold, no more auto-updates will be performed and a forced-updated will result in an exception until one or more snapshots are removed from memory. A value of zero indicates to support an unlimited amount of snapshots.

    - #### getMemoryCleanupInterval

          public Integer getMemoryCleanupInterval()

      memory cleanup tick in seconds

    - #### getNumSpinLocks

          public Integer getNumSpinLocks()

      how many spin locks each generated app will create at instantiation. Trade-off: small number implies less memory consumption. Big number implies faster execution (if algorithm uses spin locks)

    - #### getNumWorkersAnalysis

          public Integer getNumWorkersAnalysis()

      how many worker threads to use for analysis tasks

    - #### getNumWorkersFastTrackAnalysis

          public Integer getNumWorkersFastTrackAnalysis()

      how many worker threads to use for fast-track analysis tasks

    - #### getNumWorkersIo

          public Integer getNumWorkersIo()

      how many worker threads to use for I/O tasks (load/refresh/write from/to disk). This value won't affect file-based loaders, as they're always single-threaded. Database loaders will open a new connection for each I/O worker.

    - #### getParallelism

          public Integer getParallelism()

      number of worker threads to be used in thread pool. Note: if caller thread is part of another thread-pool, this value is ignored and parallelism of parent pool is used.

    - #### getParallelizationStrategy

          public ParallelizationStrategy getParallelizationStrategy()

      which parallelization strategy to use.
      `segmented` = split work into segments, use 1 thread per segment
      `task_stealing` = F/J pool using recursive actions
      `task_stealing_counted` = F/J pool using counted completers to reduce joins

    - #### getPathToGmCompiler

          public String getPathToGmCompiler()

      if set, use this path to `gm_comp` binary for dynamic compilations. If not set and `enable_gm_compiler` is `true`, PGX will try to utilize one of the built-in compiler binaries.

    - #### getReleaseMemoryThreshold

          public Double getReleaseMemoryThreshold()

      threshold percentage of used memory after which the engine starts freeing un-used graphs. Examples: A value of `0.0` means graphs get freed as soon as their reference count becomes zero. That is, all sessions which loaded that graph were destroyed/timed out. A value of `1.0` means graphs get never freed. Engine will throw `OutOfMemoryError`s as soon as a graph is needed which doesn't fit in memory anymore. A value of `0.7` means the engine keeps all graphs in memory as long as total memory consumption is below 70% of total available memory, even if there is currently no session using them. Once the 70% are surpassed and another graph needs to get loaded, un-used graphs get freed until memory consumption is below 70% again.

    - #### getSessionIdleTimeoutSecs

          public Integer getSessionIdleTimeoutSecs()

      timeout of idling sessions in seconds. Set to zero for infinity/no timeout

    - #### getSessionTaskTimeoutSecs

          public Integer getSessionTaskTimeoutSecs()

      timeout to interrupt long-running tasks submitted by sessions (algorithms, I/O tasks) in seconds. Set to zero for infinity/no timeout

    - #### getSmallTaskLength

          public Integer getSmallTaskLength()

      task length if total amount of work is small than default task length (only relevant for task-stealing strategies)

    - #### getTaskLength

          public Integer getTaskLength()

      default task length (only relevant for task-stealing strategies). F/J pool documentation says this value should be between 100 and 10000. Trade-off: small number implies more fine-grained tasks are generated, higher stealing throughput. High number implies less memory consumption and GC activity

    - #### getTmpDir

          public String getTmpDir()

      Use this path as temporary directory to store compilation artifacts and other temporary data. If set to `<system-tmp-dir>`, use standard tmp directory of underlying system (`/tmp` on Linux)

    - #### getValues

          public Map<PgxConfig.Field,Object> getValues()

      Gets the parsed values.
      Returns:
        the parsed values

    - #### getValuesWithoutDefaults

          public Map<PgxConfig.Field,Object> getValuesWithoutDefaults()

      Gets the values without defaults.
      Returns:
        the values without defaults

    - #### hasDefaultValue

          public boolean hasDefaultValue(PgxConfig.Field field)

      Checks for default value.
      Parameters:
        `field` - the field
      Returns:
        true, if value for given field is the default value

    - #### isAllowIdleTimeoutOverwrite

          public Boolean isAllowIdleTimeoutOverwrite()

      if `true`, sessions can overwrite default idle timeout

    - #### isAllowTaskTimeoutOverwrite

          public Boolean isAllowTaskTimeoutOverwrite()

      if `true`, sessions can overwrite default task timeout

    - #### isEnableGmCompiler

          public Boolean isEnableGmCompiler()

      if `true`, enable dynamic compilation of Green-Marl code during runtime. Note: the built-in Green-Marl compilers don't support all platforms. Find the list of supported platforms in the installation section. You can also use your own version of the compiler by setting the `path_to_gm_compiler` field.

    - #### isExplicitSpinLocks

          public Boolean isExplicitSpinLocks()

      `true` means spin explicitly in a loop until lock becomes available. `false` means using JDK locks which rely on the JVM to decide whether to context switch or spin. Our experiments showed that setting this value to `true` results in better performance.

    - #### isLaunchWatchdogs

          public Boolean isLaunchWatchdogs()

      (for debugging) if `true`, additional watch-dog threads will be launched which monitor and log engine health stats

    - #### isStrictMode

          public Boolean isStrictMode()

      if `true`, exceptions are thrown and logged with `ERROR` level whenever engine encounters configuration problems, such as invalid keys, mismatches and other potential errors. If `false`, engine logs problems with `ERROR`/`WARN` level (depending on severity) and makes best guesses / uses sensible defaults instead of throwing exceptions.

    - #### isThrowOutOfMemoryErrorDuringAllocation

          public Boolean isThrowOutOfMemoryErrorDuringAllocation()

      (for debugging) if `true`, engine will throw OutOfMemoryErrors on purpose when trying to allocate large memory chunks.

    - #### isThrowOutOfMemoryErrorDuringLoading

          public Boolean isThrowOutOfMemoryErrorDuringLoading()

      (for debugging) if `true`, engine will throw OutOfMemoryErrors on purpose when trying to load graphs from disk.

    - #### isThrowOutOfMemoryErrorDuringMutation

          public Boolean isThrowOutOfMemoryErrorDuringMutation()

      (for debugging) if `true`, engine will throw OutOfMemoryErrors on purpose when trying to mutate graphs.

    - #### isUnsafeAllowForeignSyntax

          public Boolean isUnsafeAllowForeignSyntax()

      (This flag reduces security, enable only if you know what you're doing!) Allow foreign syntax in user-provided Green-Marl programs

    - #### isUnsafeAllowLocalFilesystem

          public Boolean isUnsafeAllowLocalFilesystem()

      (This flag reduces security, enable only if you know what you're doing!) Allow loading from local filesystem, if in client/server mode. WARNING: This should only be enabled if you want to explicitly allow users of the PGX remote interface to access files on the local filesystem.

    - #### isUseNativeAnalysis

          public Boolean isUseNativeAnalysis()

      execute analyses using Java (`false`) or C++ (`true`) runtime

    - #### isUseNativeLoaders

          public Boolean isUseNativeLoaders()

      use Java (`false`) or C++ (`true`) graph loader framework

    - #### isUseStringPool

          public Boolean isUseStringPool()

      If `true`, PGX will store string properties in a pool in order to consume less memory on string properties

    - #### parse

          public static PgxConfig parse(InputStream is,
                        boolean strict,
                        File parent)
                                 throws IOException

      Parses an input stream.
      Parameters:
        `is` - the input stream
        `strict` - if true, parses in strict mode
        `parent` - if not null, resolves relative paths against this parent
      Returns:
        the parsed graph config
      Throws:
        `IOException` - Signals that an I/O exception has occurred.

    - #### parse

          public static PgxConfig parse(Map<String,Object> raw,
                        boolean strict,
                        File parent)

      Parses a raw key/value mapping.
      Parameters:
        `raw` - the raw key/value mapping to parse
        `strict` - if true, parses in strict mode
        `parent` - if not null, resolves relative paths against this parent
      Returns:
        the parsed graph config

    - #### parse

          public static PgxConfig parse(Properties props,
                        boolean strict)

      Parses a properties file.
      Parameters:
        `props` - the properties to parse
        `strict` - if true, parses in strict mode
      Returns:
        the parsed graph config

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

Copyright © 2015. All rights reserved.